home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / Scrap.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  12.9 KB  |  403 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        Scrap.h
  3.  
  4.      Contains:    Scrap Manager Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 9
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1985-1999 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __SCRAP__
  18. #define __SCRAP__
  19.  
  20. #ifndef __MIXEDMODE__
  21.     #include <MixedMode.h>
  22. #endif
  23.  
  24. #ifndef __MACERRORS__
  25.     #include <MacErrors.h>
  26. #endif
  27.  
  28.  
  29.  
  30.  
  31. #if PRAGMA_ONCE
  32. #pragma once
  33. #endif
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39. #if PRAGMA_IMPORT
  40. #pragma import on
  41. #endif
  42.  
  43. #if PRAGMA_STRUCT_ALIGN
  44.     #pragma options align=mac68k
  45. #elif PRAGMA_STRUCT_PACKPUSH
  46.     #pragma pack(push, 2)
  47. #elif PRAGMA_STRUCT_PACK
  48.     #pragma pack(2)
  49. #endif
  50.  
  51. /*
  52.       ________________________________________________________________
  53.       UNIVERSAL SCRAP MANAGER INTERFACES
  54.       ________________________________________________________________
  55.       The following interfaces are available when compiling for BOTH
  56.       Carbon AND Mac OS 8.
  57.       ________________________________________________________________
  58. */
  59. /*
  60.       While were in here mucking about, we defined a new type to
  61.       to put some confusion to rest. The old calls, as well as the
  62.       new calls, use the new type. Existing clients should be
  63.       blissfully ignorant.
  64. */
  65.  
  66. typedef FourCharCode                     ScrapFlavorType;
  67. /*
  68.       Newsflash! After 15 years of arduous toil, it's finally possible
  69.       for specially trained typists wielding advanced text editing
  70.       technology to define symbolic names for commonly used scrap
  71.       flavor type constants! Apple triumphs again!
  72. */
  73. enum {
  74.     kScrapFlavorTypePicture        = FOUR_CHAR_CODE('PICT'),        /* contents of a PicHandle*/
  75.     kScrapFlavorTypeText        = FOUR_CHAR_CODE('TEXT'),        /* stream of characters*/
  76.     kScrapFlavorTypeTextStyle    = FOUR_CHAR_CODE('styl'),        /* see TEGetStyleScrapHandle*/
  77.     kScrapFlavorTypeMovie        = FOUR_CHAR_CODE('moov'),        /* reference to a movie*/
  78.     kScrapFlavorTypeSound        = FOUR_CHAR_CODE('snd '),        /* see SndRecord and SndPlay*/
  79.     kScrapFlavorTypeUnicode        = FOUR_CHAR_CODE('utxt'),        /* stream of UTF16 characters*/
  80.     kScrapFlavorTypeUnicodeStyle = FOUR_CHAR_CODE('ustl')        /* ATSUI defines; Textension uses*/
  81. };
  82.  
  83. /*
  84.       If you are a Carbon client and you need to run on Mac OS 8,
  85.       you may still need to load and unload the scrap. Under Mac OS
  86.       X, the scrap is held by the pasteboard server instead of in a
  87.       handle in your app's heap, so LoadScrap and UnloadScrap do
  88.       nothing when called under Mac OS X.
  89. */
  90.  
  91. EXTERN_API( OSStatus )
  92. LoadScrap                        (void)                                                        ONEWORDINLINE(0xA9FB);
  93.  
  94. EXTERN_API( OSStatus )
  95. UnloadScrap                        (void)                                                        ONEWORDINLINE(0xA9FA);
  96.  
  97. #if CALL_NOT_IN_CARBON
  98. /*
  99.       ________________________________________________________________
  100.       MAC OS 8 SCRAP MANAGER INTERFACES
  101.       ________________________________________________________________
  102.       The following interfaces are available only when compiling for
  103.       plain vanilla Mac OS 8. We didn't add comments to them because
  104.       Inside Mac covers them in detail.
  105.       ________________________________________________________________
  106. */
  107.  
  108. struct ScrapStuff {
  109.     SInt32                             scrapSize;
  110.     Handle                             scrapHandle;
  111.     SInt16                             scrapCount;
  112.     SInt16                             scrapState;
  113.     StringPtr                         scrapName;
  114. };
  115. typedef struct ScrapStuff                ScrapStuff;
  116.  
  117. typedef ScrapStuff *                    PScrapStuff;
  118. typedef ScrapStuff *                    ScrapStuffPtr;
  119. EXTERN_API( ScrapStuffPtr )
  120. InfoScrap                        (void)                                                        ONEWORDINLINE(0xA9F9);
  121.  
  122. EXTERN_API( long )
  123. GetScrap                        (Handle                 destination,
  124.                                  ScrapFlavorType         flavorType,
  125.                                  SInt32 *                offset)                                ONEWORDINLINE(0xA9FD);
  126.  
  127. EXTERN_API( OSStatus )
  128. ZeroScrap                        (void)                                                        ONEWORDINLINE(0xA9FC);
  129.  
  130. EXTERN_API( OSStatus )
  131. PutScrap                        (SInt32                 sourceBufferByteCount,
  132.                                  ScrapFlavorType         flavorType,
  133.                                  const void *            sourceBuffer)                        ONEWORDINLINE(0xA9FE);
  134.  
  135. #endif  /* CALL_NOT_IN_CARBON */
  136.  
  137. /*
  138.       ________________________________________________________________
  139.       CARBON SCRAP MANAGER INTERFACES
  140.       ________________________________________________________________
  141.       The following interfaces are available only when compiling for
  142.       Carbon.
  143.       ________________________________________________________________
  144. */
  145.  
  146. /*
  147.       When promising a scrap flavor, it's OK if you
  148.       don't yet know how big the flavor data will be.
  149.       In this case, just pass kScrapFlavorSizeUnknown
  150.       for the flavor data size.
  151. */
  152.  
  153. enum {
  154.     kScrapFlavorSizeUnknown        = -1
  155. };
  156.  
  157. /*
  158.       kScrapReservedFlavorType is a flavor type which is reserved
  159.       for use by Scrap Manager. If you pass it to Scrap Manager,
  160.       it will be rejected.
  161. */
  162.  
  163. enum {
  164.     kScrapReservedFlavorType    = FOUR_CHAR_CODE('srft')
  165. };
  166.  
  167. /*
  168.     We've added scrap flavor flags ala Drag Manager.
  169.  
  170.     kScrapFlavorMaskNone means you want none of the flags.
  171.  
  172.     kScrapFlavorSenderOnlyMask means only the process which
  173.     put the flavor on the scrap can see it. If some other
  174.     process put a flavor with this flag on the scrap,
  175.     your process will never see the flavor, so there's
  176.     no point in testing for this flag.
  177.  
  178.     kScrapFlavorTranslated means the flavor was translated
  179.     from some other flavor in the scrap by Translation Manager.
  180.     Most callers should not care about this bit.
  181. */
  182. enum {
  183.     kScrapFlavorMaskNone        = 0x00000000,
  184.     kScrapFlavorMaskSenderOnly    = 0x00000001,
  185.     kScrapFlavorMaskTranslated    = 0x00000002
  186. };
  187.  
  188. typedef UInt32                             ScrapFlavorFlags;
  189. /*
  190.       ScrapFlavorInfo describes a single flavor within
  191.       a scrap.
  192. */
  193.  
  194. struct ScrapFlavorInfo {
  195.     ScrapFlavorType                 flavorType;
  196.     ScrapFlavorFlags                 flavorFlags;
  197. };
  198. typedef struct ScrapFlavorInfo            ScrapFlavorInfo;
  199. /*
  200.       Under a future version of Carbon, there may be multiple scraps.
  201.       We'll need ScrapRefs to tell them apart.
  202. */
  203. typedef struct OpaqueScrapRef*             ScrapRef;
  204. /*
  205.       GetCurrentScrap obtains a reference to the current scrap.
  206.       The ScrapRef obtained via GetCurrentScrap will become
  207.       invalid and unusable after the scrap is cleared.
  208. */
  209. EXTERN_API( OSStatus )
  210. GetCurrentScrap                    (ScrapRef *                scrap);
  211.  
  212. /*
  213.       GetScrapFlavorFlags tells you [a] whether the scrap contains
  214.       data for a particular flavor and [b] some things about that
  215.       flavor if it exists. This call never blocks, and is useful
  216.       for deciding whether to enable the Paste item in your Edit
  217.       menu, among other things.
  218. */
  219.  
  220. EXTERN_API( OSStatus )
  221. GetScrapFlavorFlags                (ScrapRef                 scrap,
  222.                                  ScrapFlavorType         flavorType,
  223.                                  ScrapFlavorFlags *        flavorFlags);
  224.  
  225. /*
  226.       GetScrapFlavorSize gets the size of the data of the specified
  227.       flavor. This function blocks until the specified flavor
  228.       data is available. GetScrapFlavorSize is intended as a prelude
  229.       to allocating memory and calling GetScrapFlavorData.
  230. */
  231.  
  232. EXTERN_API( OSStatus )
  233. GetScrapFlavorSize                (ScrapRef                 scrap,
  234.                                  ScrapFlavorType         flavorType,
  235.                                  Size *                    byteCount);
  236.  
  237. /*
  238.       GetScrapFlavorData gets the data from the specified flavor in the
  239.       specified scrap. This function blocks until the specified flavor
  240.       data is available. Specify the maximum size your buffer can contain;
  241.       on output, this function produces the number of bytes that were
  242.       available (even if this is more than you requested).
  243. */
  244.  
  245. EXTERN_API( OSStatus )
  246. GetScrapFlavorData                (ScrapRef                 scrap,
  247.                                  ScrapFlavorType         flavorType,
  248.                                  Size *                    byteCount,
  249.                                  void *                    destination);
  250.  
  251. /*
  252.       ClearCurrentScrap clears the current scrap. Call this
  253.       first when the user requests a Copy or Cut operation --
  254.       even if you maintain a private scrap! You should not wait
  255.       until receiving a suspend event to call ClearCurrentScrap. Call
  256.       it immediately after the user requests a Copy or Cut operation.
  257.       You don't need to put any data on the scrap immediately (although
  258.       it's perfectly fine to do so). You DO need to call GetCurrentScrap
  259.       after ClearCurrentScrap so you'll have a valid ScrapRef to pass
  260.       to other functions.
  261. */
  262.  
  263. EXTERN_API( OSStatus )
  264. ClearCurrentScrap                (void);
  265.  
  266. /*
  267.       PutScrapFlavor is a lot like PutScrap, with two differences:
  268.       we added a ScrapRef parameter at the beginning and you can
  269.       "promise" various aspects of a flavor. If you pass a NIL
  270.       data pointer, this is a promise that in the future you
  271.       will provide data for this flavor. Provide the data
  272.       through a subsequent call to PutScrapFlavor, either later
  273.       in the same code flow or during a scrap promise keeper proc.
  274.       If you know how big the data is, you can pass the size as
  275.       well, and this may allow subsequent callers of GetScrapFlavorInfo
  276.       to avoid blocking. If you don't know the size, pass -1.
  277.       If you pass a 0 size, you are telling Scrap Manager not to
  278.       expect any data for this flavor. In this case, the flavor
  279.       data pointer is ignored. NOTE: the last time you can provide
  280.       scrap flavor data is when your scrap promise keeper gets
  281.       called. It is NOT possible to call PutScrapFlavor while
  282.       handling a suspend event; suspend events under Carbon
  283.       simply don't work the way they do under Mac OS 8.
  284. */
  285.  
  286. EXTERN_API( OSStatus )
  287. PutScrapFlavor                    (ScrapRef                 scrap,
  288.                                  ScrapFlavorType         flavorType,
  289.                                  ScrapFlavorFlags         flavorFlags,
  290.                                  Size                     flavorSize,
  291.                                  const void *            flavorData) /* can be NULL */;
  292.  
  293. /*
  294.       ScrapPromiseKeeper is a function you write which is called by
  295.       Scrap Manager as needed to keep your earlier promise of a
  296.       particular scrap flavor. When your function is called, deliver
  297.       the requested data by calling PutScrapFlavor.
  298. */
  299.  
  300. typedef CALLBACK_API( OSStatus , ScrapPromiseKeeperProcPtr )(ScrapRef scrap, ScrapFlavorType flavorType, void *userData);
  301. typedef STACK_UPP_TYPE(ScrapPromiseKeeperProcPtr)                 ScrapPromiseKeeperUPP;
  302. #if OPAQUE_UPP_TYPES
  303.     EXTERN_API(ScrapPromiseKeeperUPP)
  304.     NewScrapPromiseKeeperUPP       (ScrapPromiseKeeperProcPtr userRoutine);
  305.  
  306.     EXTERN_API(void)
  307.     DisposeScrapPromiseKeeperUPP    (ScrapPromiseKeeperUPP    userUPP);
  308.  
  309.     EXTERN_API(OSStatus)
  310.     InvokeScrapPromiseKeeperUPP       (ScrapRef                scrap,
  311.                                     ScrapFlavorType            flavorType,
  312.                                     void *                    userData,
  313.                                     ScrapPromiseKeeperUPP    userUPP);
  314.  
  315. #else
  316.     enum { uppScrapPromiseKeeperProcInfo = 0x00000FF0 };             /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  317.     #define NewScrapPromiseKeeperUPP(userRoutine)                     (ScrapPromiseKeeperUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppScrapPromiseKeeperProcInfo, GetCurrentArchitecture())
  318.     #define DisposeScrapPromiseKeeperUPP(userUPP)                     DisposeRoutineDescriptor(userUPP)
  319.     #define InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userUPP)  (OSStatus)CALL_THREE_PARAMETER_UPP((userUPP), uppScrapPromiseKeeperProcInfo, (scrap), (flavorType), (userData))
  320. #endif
  321. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  322. #define NewScrapPromiseKeeperProc(userRoutine)                     NewScrapPromiseKeeperUPP(userRoutine)
  323. #define CallScrapPromiseKeeperProc(userRoutine, scrap, flavorType, userData) InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userRoutine)
  324. /*
  325.       SetScrapPromiseKeeper associates a ScrapPromiseKeeper with a
  326.       scrap. You can remove a ScrapPromiseKeeper from a scrap by
  327.       passing a NIL ScrapPromiseKeeper to SetScrapPromiseKeeper.
  328.       Pass whatever you like in the last parameter; its value will
  329.       be passed to your ScrapPromiseKeeper, which can do whatever
  330.       it likes with the value. You might choose to pass a pointer
  331.       or handle to some private scrap data which the
  332.       ScrapPromiseKeeper could use in fabricating one or more
  333.       promised flavors.
  334. */
  335. EXTERN_API( OSStatus )
  336. SetScrapPromiseKeeper            (ScrapRef                 scrap,
  337.                                  ScrapPromiseKeeperUPP     upp,
  338.                                  const void *            userData);
  339.  
  340. /*
  341.       GetScrapFlavorCount produces the number of
  342.       items which can be obtained by GetScrapFlavorInfoList.
  343. */
  344.  
  345. EXTERN_API( OSStatus )
  346. GetScrapFlavorCount                (ScrapRef                 scrap,
  347.                                  UInt32 *                infoCount);
  348.  
  349. /*
  350.       GetScrapFlavorInfoList fills a list (array)
  351.       of items which each describe the corresponding
  352.       flavor in the scrap. It fills no more array
  353.       elements as are specified. On exit, it produces
  354.       the count of elements it filled (which may be
  355.       smaller than the count requested). Yes, YOU
  356.       must provide the memory for the array.
  357. */
  358.  
  359. EXTERN_API( OSStatus )
  360. GetScrapFlavorInfoList            (ScrapRef                 scrap,
  361.                                  UInt32 *                infoCount,
  362.                                  ScrapFlavorInfo         info[]);
  363.  
  364.  
  365. /*
  366.       CallInPromises forces all promises to be kept.
  367.       If your application promises at least one flavor
  368.       AND it does NOT adopt the new event model, you
  369.       should call this function when your application
  370.       is about to quit. If your app promises no flavors,
  371.       there is no need to call this function, and if
  372.       your app adopts the new event model, this function
  373.       will be called automagically for you. It doesn't
  374.       hurt to call this function more than once, though
  375.       promise keepers may be asked to keep promises
  376.       they already tried and failed.
  377. */
  378.  
  379. EXTERN_API( OSStatus )
  380. CallInScrapPromises                (void);
  381.  
  382.  
  383. #if PRAGMA_STRUCT_ALIGN
  384.     #pragma options align=reset
  385. #elif PRAGMA_STRUCT_PACKPUSH
  386.     #pragma pack(pop)
  387. #elif PRAGMA_STRUCT_PACK
  388.     #pragma pack()
  389. #endif
  390.  
  391. #ifdef PRAGMA_IMPORT_OFF
  392. #pragma import off
  393. #elif PRAGMA_IMPORT
  394. #pragma import reset
  395. #endif
  396.  
  397. #ifdef __cplusplus
  398. }
  399. #endif
  400.  
  401. #endif /* __SCRAP__ */
  402.  
  403.